# ZIP : ZIP package management

The Zip module provides the operation of a '.zip' file compression package. You can compress and decompress the zip package, also can extract, add and traverse the files in the zip package.

User can use the following code to import the Zip module.

var Zip = require('zip');

# Support

The following shows Zip module APIs available for each permissions.

# Zip Class

# new Zip(zipFile[, mode[, level]])

• zipFile {String} Zip file path.
• mode {String} Open mode. default: 'r'.
• level {Integer} The level of compression used when creating the zip file. Must in 0 ~ 9.

mode can be:

Opens zip archive with compression level using the given mode.

# Example

// Create a new zip file using default level.
var zip = new Zip('a.zip', 'w');

// Open a exists zip file.
var zip = new Zip('b.zip');

# Zip.extract(zipFile, dir)

• zipFile {String} An existing zip file path.
• dir {String} Unzipped target directory.
• Returns: {Boolean} Whether the extraction is successful.

Extract all files from the specified zip package to the specified directory.

# Example

Zip.extract('b.zip', './b');

# Zip.compress(zipFile, dir[, level])

• zipFile {String} New zip file path.
• dir {String} Zipped source directory.
• Returns: {Boolean} Whether the compress is successful.

Compress all files in the specified directory and add them to a specified zip file.

# Example

Zip.compress('c.zip', './b');

# Zip Object

# zip.open(index)

• index {Integer} File index in zip package.
• Returns: {Boolean} Whether the open is successful.

Open the file of the specified index in zip package.

# Example

// Open a exists zip file.
var zip = new Zip('b.zip');

zip.open(0);

# zip.open(fileName)

• fileName {String} File name in zip package.
• Returns: {Boolean} Whether the open is successful.

Open the file of the specified file name in zip package.

# Example

// Open a exists zip file.
var zip = new Zip('b.zip');

// The specified file must exist in the zip package.
zip.open('aaa.txt');
zip.close();

zip.open('dir/bbb.txt');
zip.close();

# zip.close()

Close the currently open file in zip package.

# zip.end()

Destruct the zip object, write the data in the cache back to the disk and release zip data cache.

# Example

var zip = new Zip('b.zip');

// Various zip operations

zip.end();

# zip.stat()

• Returns: {Object} File state in zip packege.

The returns object includes following members:

• name File name.
• index Index.
• size Original file size.
• mode File mode. Please refer to the fs module fs.stat() function return object mode field.

Get the current open file status information in zip packege.

# Example

var zip = new Zip('b.zip');

zip.open(0);
var stat = zip.stat();
if (stat) {
  console.log('Sub file name:', stat.name);
  console.log('Sub file index:', stat.index);
  console.log('Sub file size:', stat.size);
  if (fs.S_ISDIR(stat.mode)) {
    console.log('Sub file is directory.');
  } else {
    console.log('Sub file is file.');
  }
}
zip.end();

# zip.read()

• Returns: {Buffer} File content.

Read the contents of the currently open file and return a buffer object.

# Example

var zip = new Zip('b.zip');

zip.open('aaa.txt');
var buf = zip.read();
zip.end();

console.log(buf.toString());

# zip.fread(targetFile[, opt])

• targetFile {String} Target file path.
• opt {Object} File options.
• Returns: {Boolean} Whether the file extract is successful.

Extract the currently open file in zip package to the specified target.

The opt object can contain the following members:

• mode {Integer} File mode, if not specified, use the mode info in the archive.
• uid {Integer} File owner user ID, if not specified, the current user UID will be used.
• gid {Integer} File owner group ID, if not specified, the current user GID will be used.

# Example

var zip = new Zip('b.zip');

zip.open('aaa.txt');
zip.fread('aaa.txt'); // Extract aaa.txt
zip.end();

# zip.write(string)

• string {String} The string to be written.
• Returns: {Integer} Actual number of bytes written, equal to string.byteLength is successed.

Write the specified string to the currently open zip internal file.

# Example

var zip = new Zip('a.zip', 'w');

zip.open('aaa.txt');
zip.write('AAAA');
zip.end();

# zip.write(buffer[, offset[, length]])

• buffer {Buffer} Write data buffer.
• offset {Integer} Buffer offset. default:0.
• length {Integer} Write length. default:buffer.length.
• Returns: {Integer} Actual number of bytes written, equal to buffer.length is successed.

Write the specified data to the currently open zip internal file.

# Example

var zip = new Zip('a.zip', 'w');

zip.open('aaa.txt');
zip.write(new Buffer('test'));
zip.end();

# zip.fwrite(srcFile)

• srcFile {String} Specified source file.
• Returns: {Boolean} Whether the file compress is successful.

Add the specified srcFile to the zip package.

# Example

var zip = new Zip('a.zip', 'w');

zip.open('aaa.txt');
zip.fwrite('aaa.txt'); // Compress aaa.txt
zip.end();

# zip.fdump(callback)

• callback {Function} Callback function.
  • data {Buffer} File data in zip.
  • offset {Integer} Data offset of current zip file.

Traverse the currently zip read file and put the content of the file to the callback function. Multiple callbacks will be generated when the file content is large. It is mostly used to calculate file hash value before file decompression.

# Example

var zip = new Zip('b.zip');

zip.open('aaa.txt');
zip.fdump(function(data) {
  console.log(data.length);
});
zip.end();

# zip.count()

• Returns: {Integer} The total number of files in the current zip package.

Get The total number of files in the current zip package.